﻿//-----------------------------------------------------------------------------------------
// <copyright file="LightSensor.cs" company="Jakub Florczyk (www.jakubflorczyk.pl)">
//      Copyright © 2009 Jakub Florczyk (www.jakubflorczyk.pl)
//      http://samsungmobilesdknet.codeplex.com
// </copyright>
//-----------------------------------------------------------------------------------------

namespace SamsungMobileSDKNET
{
    using System.Runtime.InteropServices;

    /// <summary>
    /// Specifies the capabilities of the light sensor. Illuminance values are given in Lux (lumens per square meter). Lumens are a measure of perceived light.
    /// </summary>
    [StructLayout(LayoutKind.Sequential)]
    public struct LightSensorCapabilities
    {
        /// <summary>
        /// Minimum possible illuminance the sensor is capable of measuring.
        /// </summary>
        public uint MinIlluminance;

        /// <summary>
        /// Maximum possible illuminance the sensor is capable of measuring.
        /// </summary>
        public uint MaxIlluminance;
    }

    /// <summary>
    /// Samsung Light Sensor API.
    /// </summary>
    /// <remarks>
    /// The Light Sensor API gives an application access to the illuminance measured by the device’s light sensor. The illuminance is given in lux; the range and precision of this value can vary from device to device. 
    /// </remarks>
    public class LightSensor
    {
        /// <summary>
        /// Gets the capabilities of the light sensor.
        /// </summary>
        /// <param name="capabilities">A pointer to the capabilities of the device.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiLightSensorGetCapabilities")]
        public static extern ResultCode GetCapabilities(
            [Out] out LightSensorCapabilities capabilities);

        /// <summary>
        /// Retrieives the illuminance detected by the sensor in units of Lux.
        /// </summary>
        /// <param name="illuminance">A pointer to the illuminance.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiLightSensorGetIlluminance")]
        public static extern ResultCode GetIlluminance(
            [Out] out uint illuminance);        
    }
}
